The present disclosure generally relates to systems for generating documentation for source code, and more particularly relates to an information processing system that automatically generates human readable and meaningful documentation for one or more related source code files.
Understanding design structure, features, and function, and the associated run time behavior, of sparsely, if at all, documented applications can be very challenging. This is mainly due to the lack of human readable and meaningful documentation that describes the source code of such applications. These types of descriptions of the source code artifacts (SCA) are typically included in source code artifact (SCA) documentation. Users, programmers, and system administration personnel, all have varying degrees of need to read such comments to help them understand the design structure and function, and the associated run time behavior, of such applications.
The current art is exemplified by Javadoc and Doxygen, which generate documents for Java and C++ source code, respectively. These tools generate HTML documents that structure and format descriptive text embodied in comments in the source code. The comments are authored by computer programmers while developing the code. In practice, much of the source code produced, even for commercial products, lacks comments or contains comments that are insufficient with respect to detail or accuracy. Even when comments are provided, they often become inaccurate when the source code is subsequently modified.
This lack of user readable and meaningful comments associated with applications is a particularly pernicious problem for long running applications with strong run-time dynamics with a continuing need to capture and maintain such comments describing the history of changes in source code and runtime behavior that happen during the execution of the application. Furthermore, significant changes in the runtime behavior, such as variations in the application topology, workload, or runtime state and metrics, can be difficult to digest by a human operator without such user readable and meaningful documentation and comments.
This lack of source code artifacts documentation results in source code which typically consists of lists of classes and method names, but is otherwise lacking in meaningful or accurate descriptions. Other programmers, system administrators, IT managers, or customers who intend to use or understand the code need to resort to inferring the structure, features, and function by guessing and experimenting, reading the source code, if available, or referring to help resources such as forums and the vendor's help desk.
While the size and complexity of applications continues to increase, the importance of user readable and meaningful comments associated with the source code artifacts of such applications becomes more important. Unfortunately, conventional information processing systems have not kept up with this increasing need for generating user readable and meaningful documentation for source code modules.